home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / tcl / Tcl_CreateCommand.man < prev    next >
Encoding:
Text File  |  1990-02-28  |  7.2 KB  |  201 lines
  1.  
  2.  
  3.  
  4. Tcl_CreateCommand Tcl Command Language Library  Tcl_CreateCommand
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NNAAMMEE
  11.      Tcl_CreateCommand - define an  application-specific  command
  12.      binding
  13.  
  14. SSYYNNOOPPSSIISS
  15.      ##iinncclluuddee <<ttccll..hh>>
  16.  
  17.      TTccll__CCrreeaatteeCCoommmmaanndd(_i_n_t_e_r_p, _c_m_d_N_a_m_e, _p_r_o_c, _c_l_i_e_n_t_D_a_t_a, _d_e_l_e_t_e_P_r_o_c)
  18.  
  19. AARRGGUUMMEENNTTSS
  20.      Tcl_Interp   *_i_n_t_e_r_p           (in)      Interpreter      in
  21.                                               which to create new
  22.                                               command.
  23.  
  24.      char         *_c_m_d_N_a_m_e          (in)      Name  of  new  com-
  25.                                               mand.
  26.                                               Tcl_CreateCommand
  27.                                               makes   a  copy  of
  28.                                               this value for  its
  29.                                               own use.
  30.  
  31.      int          (*_p_r_o_c)()         (in)      Implementation   of
  32.                                               new  command:  _p_r_o_c
  33.                                               will   be    called
  34.                                               whenever _c_m_d_N_a_m_e is
  35.                                               invoked as  a  com-
  36.                                               mand.
  37.  
  38.      ClientData   _c_l_i_e_n_t_D_a_t_a        (in)      Arbitrary  one-word
  39.                                               value  to  pass  to
  40.                                               _p_r_o_c            and
  41.                                               _d_e_l_e_t_e_P_r_o_c.
  42.  
  43.      void         (*_d_e_l_e_t_e_P_r_o_c)()   (in)      Procedure  to  call
  44.                                               before  _c_m_d_N_a_m_e  is
  45.                                               deleted  from   the
  46.                                               interpreter; allows
  47.                                               for        command-
  48.                                               specific   cleanup.
  49.                                               If  NULL,  then  no
  50.                                               procedure is called
  51.                                               before the  command
  52.                                               is deleted.
  53.  
  54. _________________________________________________________________
  55.  
  56.  
  57. DDEESSCCRRIIPPTTIIOONN
  58.      TTccll__CCrreeaatteeCCoommmmaanndd defines a new command in _i_n_t_e_r_p and  asso-
  59.      ciates  it with procedure _p_r_o_c such that whenever _c_m_d_N_a_m_e is
  60.      invoked as a Tcl command (via a call to  TTccll__EEvvaall)  the  Tcl
  61.      interpreter will call _p_r_o_c to process the command.  If there
  62.  
  63.  
  64.  
  65. Sprite v.1.0       Printed:  February 28, 1990                  1
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72. Tcl_CreateCommand Tcl Command Language Library  Tcl_CreateCommand
  73.  
  74.  
  75.  
  76.      is already a command  _c_m_d_N_a_m_e  associated  with  the  inter-
  77.      preter,  it  is  deleted.   _P_r_o_c  should  have the following
  78.      structure:
  79.           int
  80.           proc(_c_l_i_e_n_t_D_a_t_a, _i_n_t_e_r_p, _a_r_g_c, _a_r_g_v)
  81.                ClientData _c_l_i_e_n_t_D_a_t_a;
  82.                Tcl_Interp *_i_n_t_e_r_p;
  83.                int _a_r_g_c;
  84.                char *_a_r_g_v[];
  85.           {
  86.           }
  87.      The _c_l_i_e_n_t_D_a_t_a and  _i_n_t_e_r_p  parameters  are  copies  of  the
  88.      _c_l_i_e_n_t_D_a_t_a  and _i_n_t_e_r_p arguments given to TTccll__CCrreeaatteeCCoommmmaanndd.
  89.      Typically, _c_l_i_e_n_t_D_a_t_a points to an application-specific data
  90.      structure  that  describes  what to do when the command pro-
  91.      cedure is invoked.  _A_r_g_c and _a_r_g_v describe the arguments  to
  92.      the  command, _a_r_g_c giving the number of arguments (including
  93.      the command name) and _a_r_g_v giving the values  of  the  argu-
  94.      ments  as  strings.   The  _a_r_g_v  array  will  contain _a_r_g_c+1
  95.      values; the first _a_r_g_c values point to the argument strings,
  96.      and the last value is NULL.
  97.  
  98.      _P_r_o_c must return an integer  code  that  is  either  TTCCLL__OOKK,
  99.      TTCCLL__EERRRROORR,  TTCCLL__RREETTUURRNN, TTCCLL__BBRREEAAKK, or TTCCLL__CCOONNTTIINNUUEE.  See the
  100.      Tcl overview man page for details on what these codes  mean.
  101.      Most  normal  commands will only return TTCCLL__OOKK or TTCCLL__EERRRROORR.
  102.      In addition, _p_r_o_c must set  _i_n_t_e_r_p->_r_e_s_u_l_t  to  point  to  a
  103.      string value; in the case of a TTCCLL__OOKK return code this gives
  104.      the result of the command, and in the case of  TTCCLL__EERRRROORR  it
  105.      gives  an  error message.  The TTccll__RReettuurrnn procedure provides
  106.      an easy interface for setting the return  value;   for  com-
  107.      plete  details  on  how the _i_n_t_e_r_p->_r_e_s_u_l_t field is managed,
  108.      see the TTccll__IInntteerrpp man page.  Before invoking a command pro-
  109.      cedure,  TTccll__EEvvaall  sets  _i_n_t_e_r_p->_r_e_s_u_l_t to point to an empty
  110.      string, so simple commands can return  an  empty  result  by
  111.      doing nothing at all.
  112.  
  113.      The contents of the _a_r_g_v array are copies made  by  the  Tcl
  114.      interpreter  for the use of _p_r_o_c.  _P_r_o_c may alter any of the
  115.      strings in _a_r_g_v.  However, the _a_r_g_v  array  is  recycled  as
  116.      soon as _p_r_o_c returns, so _p_r_o_c must not set _i_n_t_e_r_p->_r_e_s_u_l_t to
  117.      point anywhere within the _a_r_g_v values (call Tcl_Return  with
  118.      status TTCCLL__VVOOLLAATTIILLEE if you want to return something from the
  119.      _a_r_g_v array).
  120.  
  121.      _D_e_l_e_t_e_P_r_o_c will be invoked when  (if)  _c_m_d_N_a_m_e  is  deleted.
  122.      This  can  occur  through  a  call  to  TTccll__DDeelleetteeCCoommmmaanndd or
  123.      TTccll__DDeelleetteeIInntteerrpp, or by replacing _c_m_d_N_a_m_e in another call to
  124.      Tcl_CreateCommand.  _D_e_l_e_t_e_P_r_o_c is invoked before the command
  125.      is deleted, and gives  the  application  an  opportunity  to
  126.      release   any   structures   associated  with  the  command.
  127.      _D_e_l_e_t_e_P_r_o_c should have the following form:
  128.  
  129.  
  130.  
  131. Sprite v.1.0       Printed:  February 28, 1990                  2
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138. Tcl_CreateCommand Tcl Command Language Library  Tcl_CreateCommand
  139.  
  140.  
  141.  
  142.           void
  143.           deleteProc(_c_l_i_e_n_t_D_a_t_a)
  144.                ClientData _c_l_i_e_n_t_D_a_t_a;
  145.           {
  146.           }
  147.      The _c_l_i_e_n_t_D_a_t_a argument will be the same as  the  _c_l_i_e_n_t_D_a_t_a
  148.      argument passed to TTccll__CCrreeaatteeCCoommmmaanndd.
  149.  
  150.  
  151. KKEEYYWWOORRDDSS
  152.      bind, command, create, interpreter
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197. Sprite v.1.0       Printed:  February 28, 1990                  3
  198.  
  199.  
  200.  
  201.